<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <title>Couchdbkit - Listen to database changes</title>
    <!--[if IE]>

    <script>
        // allow IE to recognize HTMl5 elements
        document.createElement('section');
        document.createElement('article');
        document.createElement('aside');
        document.createElement('footer');
        document.createElement('header');
        document.createElement('nav');
        document.createElement('time');

    </script>
    <![endif]-->

    <link rel="stylesheet" href="/css/couchdbkit.css?20090615" type="text/css" media="screen, projection" />
    <link rel="stylesheet" href="/static/css/print.css?20090615" type="text/css" media="print" />
    <script type="text/javascript" src="/js/prettify.js"></script>
    
    <link rel="alternate" type="application/rss+xml" title="RSS 2.0" href="/feed.xml" />
    

    
        
</head>
<body onload="prettyPrint()">
    
    <div class="container">
        <header id="site_header">
            <h1><a href="/"><span>couchdbkit</span></a></h1>
            <ul id="main_nav">
                <li><a href="/">home</a></li>
                <li><a href="/blog/">news</a></li>
                <li><a href="/download.html">download</a></li>
                <li><a href="/docs/">documentation</a></li>
                <li><a href="/docs/api/">API</a></li>
            </ul>

        </header>
        
        
        
        
        <aside id="sidebar">
            <ul class="sidenav">
                <li><a href="/blog/">Latest news</a></li>
                <li><a href="/download.html">Download latest</a></li>
                <li><a href="/docs/gettingstarted.html">Getting started</a></li>
                <li><a href="/docs/faq.html">Frequently Asked Questions</a></li>
                <li><a href="/docs/about.html">About couchdbkit</a></li>
                <li><a href="/contact.html">Getting help with couchdbkit</a></li>
            </ul>
            <div class="info">
                <h3>Getting started</h3>
                <p>See the <a href="/download.html">download instructions</a> for information on getting couchdbkit, and read the <a href="/docs/gettingstarted.html">getting started</a> instructions to start programming CouchDB in your own application in less than 10 minutes.</p>
            </div>
            <div class="info">
                <h3>Get involved</h3>
                <ul>
                    <li><p><a href="http://webchat.freenode.net/?channels=couchdbkit">#couchdbkit IRC channel</a>: chat with other couchdbkit users</p></li>
                    <li><p><a href="http://github.com/benoitc/couchdbkit/issues">Ticket system</a>: report bugs and make feature requests</p></li>
                    <li><p><a href="http://groups.google.com/group/couchdbkit">Mailing-List</a>: The main list for help and follow changes.</p></li>
                </ul>
                        
            </div>
           
        </aside>
        
    
        
<section id="content">
    <article>
        <h1>Listen to database changes</h1>
        	<p>Since the <a href="http://couchdb.apache.org/downloads.html">0.10 release</a> of CouchDB, it&#8217;s possible to listen on <a href="http://wiki.apache.org/couchdb/HTTP_database_API#Changes">db changes</a> via the <span class="caps">REST</span> api. </p>

	<p>The `couchdbkit.Consumer` object provides you a way to listen on these changes asynchronously (continuous changes) or just wait for one change (longpolling). You can of course just fetch changes since the last update sequence.</p>

	<h1><span class="caps">DEPRECATED</span></h1>

	<p>This api is now deprecated. Since the changes <span class="caps">API</span> instead.</p>

	<h2>Create a consumer</h2>

	<p>To create a consumer, instantiate the `couchdbkit.Consumer` object like this.</p>

<pre class="code prettyprint">
	>>> from couchdbkit import Server, Consumer
	>>> s = Server()
	>>> db = s.create_db(&#8220;mydb&#8221;)
	>>> c = Consumer(db)
</pre>

	<p>A consumer object is initialized with the db instance on which you want<br />to listen changes. The default backend use standard library asyncore,<br />but you can also use gevent and eventlet backend:</p>

<pre class="code prettyprint">
    >>>  c = Consumer(db, backend='gevent&#8217;)
</pre>

	<h2>Fetch changes</h2>

<pre class="code prettyprint">
	>>> db.save_doc({})
	{'rev&#8217;: &#8217;1-967a00dff5e02add41819138abb3284d&#8217;,
	 'ok&#8217;: True, 'id&#8217;: 'e3453543865212eede756809f71436c5&#8217;}
	>>> db.save_doc({})
	{'rev&#8217;: &#8217;1-967a00dff5e02add41819138abb3284d&#8217;, 
	'ok&#8217;: True, 'id&#8217;: 'b0ec8a9287cc53b00c1d621720e8144d&#8217;}
	>>> c.fetch(since=0)
	{'last_seq&#8217;: 2, 'results&#8217;: [{'changes&#8217;: 
	[{'rev&#8217;: &#8217;1-967a00dff5e02add41819138abb3284d&#8217;}], 
	'id&#8217;: 'e3453543865212eede756809f71436c5&#8217;, 'seq&#8217;: 1}, 
	{'changes&#8217;: [{'rev&#8217;: &#8217;1-967a00dff5e02add41819138abb3284d&#8217;}], 
	'id&#8217;: 'b0ec8a9287cc53b00c1d621720e8144d&#8217;, 'seq&#8217;: 2}]}
</pre>

	<p>Here we get all changes since the db has been created via `fetch` method of `Consumer` instance.</p>

	<h3>Listen for changes</h3>

	<p>There are 2 possibilities in CouchDB to listen for changes. You can wait until a change happen in the db (longpolling) and close connection or you can just listen on each changes events and handle them in one function.</p>

	<p>To wait for a change you may want to use the `wait_once` function. To wait a change since the last sequence: </p>

<pre class="code prettyprint">
 >>> c.wait_once(since=2)
 {'last_seq&#8217;: 3, 'results&#8217;: [{'changes&#8217;: 
 [{'rev&#8217;: &#8217;1-967a00dff5e02add41819138abb3284d&#8217;}], 
 'id&#8217;: '70958b546d1f214d221c6a16648d3a2b&#8217;, 'seq&#8217;: 3}]}
</pre>

	<p>`wait_once` will wait until a change happen or until connection timeout. Using `timeout` args or `heartbeat` you can set timeout or keep connection open.</p>

	<p>To listen on changes asynchronously and react on them, you have to use the `wait` method. This method using Python `asyncore` module, will wait on new changes lines and send these lines to the functions you registered as callaback :</p>

<pre class="code prettyprint">
 >>> def print_line(line):
 ...     print &#8220;got %s&#8221; % line
 ... 
 >>> c.register_callback(print_line)
 >>> c.wait() # Go into receive loop
</pre>

	<p>By default it will wait infinitely, connection is kept alive.</p>

	<h2>Filter changes</h2>

	<p>`wait_once` and `wait` method allow you to use design docs filter&#8217;s functions to filter changes. Ex:</p>

<pre class="code prettyprint">
 >>> c.wait(filter_name=&#8220;mydesign/filtername&#8221;)
</pre>

	<p>`filter_name` argument take the design doc name and filter function name as string.</p>
    </article>
</section>

        
        <footer id="bottom">
            <p class="copyright">2008-2012 &copy; <a href="http://benoitc.org">Benoît Chesneau</a> - Some rights reserved.</p>
            <div id="cc"><a rel="license" href="http://creativecommons.org/licenses/by/2.0/fr/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by/2.0/fr/80x15.png" /></a> This <span xmlns:dc="http://purl.org/dc/elements/1.1/" href="http://purl.org/dc/dcmitype/InteractiveResource" rel="dc:type">website</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/2.0/fr/">Creative Commons Attribution 2.0 France License</a>.</div>
            <p>Hosted on <a href="http://github.com/">GitHub</a></p>
        </footer>
        
    </div>

    
    
    
</body>
</html>